home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / Pasc / TN.PASC.010 < prev    next >
Encoding:
Text File  |  1989-04-22  |  37.1 KB  |  768 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Pascal
  8. #10:    Configuration and Use of the Apple II Pascal Run-Time Systems
  9.  
  10. Revised by:    Cheryl Ewy                                       November 1988
  11. Revised by:    Cheryl Ewy                                           June 1985
  12.  
  13. This Technical Note describes the Apple II Pascal Run-Time Systems which 
  14. permit the "turnkey" execution of application software which has been 
  15. developed using Apple Pascal.
  16. _____________________________________________________________________________
  17.  
  18.  
  19. System Overview
  20.  
  21. The Run-Time Systems support only the execution of an application package.  
  22. Unlike the Pascal Development System, the Run-Time Systems do not contain the 
  23. Assembler, Compiler, Editor, Filer or Linker, nor even an error reporting 
  24. mechanism at the system level.  System operations such as transferring files, 
  25. compacting disks (Krunching), and the reporting of and recovery from errors, 
  26. are all left to the application program.  It is the software developer's 
  27. responsibility to design and implement friendly, entirely self-contained 
  28. packages for use with the Run-Time Systems.  The safest assumption to make 
  29. when developing such packages is that the user is not only unfamiliar with the 
  30. facilities of the Pascal Development System, but may also be ignorant of 
  31. computer operation and use in general. 
  32.  
  33. The three run-time systems currently available are :
  34.  
  35. o    The 48K Run-Time System  V1.2    (standard and stripped)
  36. o    The 64K Run-Time System  V1.3    (standard only)
  37. o    The 128K Run-Time System V1.3    (standard only)
  38.  
  39. The name of each Run-Time System indicates the minimum amount of RAM necessary 
  40. for proper operation.  Any additional RAM available will not be used by the 
  41. Run-Time Systems.
  42.  
  43. The 48K Run-Time System has not been updated to version 1.3, as have the 64K 
  44. and 128K Run-Time Systems.  Thus, the changes and improvements made to Pascal 
  45. for version 1.3 are not available in the 48K Run-Time System.  Specifically, 
  46. the 48K Run-Time System can only use Disk II drives and can only boot from 
  47. slot 6.  See the Apple II Pascal 1.3 Manual for more information on the 
  48. differences between versions 1.2 and 1.3 of Apple II Pascal.
  49.  
  50. There are two configurations of the 48K Run-Time System available, one of 
  51. which provides more free memory for the application package's programs and 
  52. data than does the other.  Except as noted later, the standard configuration 
  53. of the Run-Time System supports all features of the Pascal Development System 
  54. that are relevant to turnkey execution of application software.  The stripped 
  55. configuration lacks set operations and floating-point arithmetic.
  56.  
  57.  
  58. Contents of the Apple II Pascal Run-Time System Disks
  59.  
  60. The following files are contained on the Apple II Pascal 1.2 48K Run-Time 
  61. System disk (RT48:):
  62.  
  63. o    RTSTND.APPLE       48K Run-time standard P-machine.
  64. o    RTSTRP.APPLE       48K Run-time stripped P-machine.
  65. o    SYSTEM.PASCAL      48K Run-time operating system.
  66. o    RTBSTND.BOOT       Contains the boot code for RTSTND.APPLE.
  67. o    RTBSTRP.BOOT       Contains the boot code for RTSTRP.APPLE.
  68. o    RTBOOTLOAD.CODE    Utility program to load 48K Run-time boot 
  69.                         code onto blocks 0 and 1 of Vendor Product 
  70.                         disk. 
  71.  
  72. The following files are described below:
  73.  
  74. o    SYSTEM.LIBRARY
  75. o    SYSTEM.ATTACH 
  76. o    RTSETMODE.CODE
  77. o    II40.MISCINFO 
  78. o    II80.MISCINFO 
  79. o    IIE40.MISCINFO 
  80. o    SYSTEM.MISCINFO
  81. o    SYSTEM.CHARSET
  82.  
  83. The following files are contained on the Apple II Pascal 1.3 64K Run-Time 
  84. System disk (RT64:):
  85.  
  86. o    SYSTEM.APPLE       64K Run-time standard P-machine.
  87. o    SYSTEM.PASCAL      64K Run-time operating system.
  88.  
  89. The following files are described below:
  90.  
  91. o    SYSTEM.LIBRARY
  92. o    SYSTEM.ATTACH
  93. o    RTSETMODE.CODE
  94. o    II40.MISCINFO
  95. o    II80.MISCINFO
  96. o    SYSTEM.MISCINFO
  97. o    SYSTEM.CHARSET
  98.  
  99. The following files are contained on the Apple II Pascal 1.3 128K Run-Time 
  100. System disk (RT128:):
  101.  
  102. o    SYSTEM.APPLE       128K Run-time standard P-machine.
  103. o    SYSTEM.PASCAL      128K Run-time operating system.
  104.  
  105. The following files are described below, and are identical to the 64K Run-Time 
  106. System files:
  107.  
  108. o    SYSTEM.LIBRARY
  109. o    SYSTEM.ATTACH
  110. o    RTSETMODE.CODE
  111. o    SYSTEM.MISCINFO
  112. o    SYSTEM.CHARSET
  113.  
  114. The Development Systems referred to in the following file descriptions are the 
  115. Apple II Pascal 1.3 Development System when discussing files on the 64K and 
  116. the 128K Run-Time System disks and the Apple II Pascal 1.2 Development System 
  117. when discussing files on the 48K Run-Time System disk.
  118.  
  119. SYSTEM.LIBRARY    contains the run-time versions of the same Intrinsic 
  120.                   Units supplied with the Development System.  These 
  121.                   Units are for use only with the Run-Time System and 
  122.                   will not execute properly in the Development 
  123.                   environment.  Conversely, only the Units in this 
  124.                   library, not those on the Development System disks, 
  125.                   should be used when executing programs in the Run-time 
  126.                   environment.  Note  that the developer is free to add 
  127.                   his own Intrinsic Units to SYSTEM.LIBRARY.
  128. SYSTEM.ATTACH     is a run-time version of the dynamic driver-attachment 
  129.                   program described in Apple II Pascal Device and 
  130.                   Interrupt Support Tools.  This version may only be 
  131.                   used with the Run-Time Systems.
  132. RTSETMODE.CODE    is a utility program that permits the vendor to arm or 
  133.                   disarm any or all of four system options:  Filehandler 
  134.                   Overlay, Single Drive System, Ignore External 
  135.                   Terminal, and Get/Put and Filehandler Overlay.
  136. MISCINFO          files are identical to those supplied on the 
  137.                   Development System disks and are supplied here only 
  138.                   for the sake of redundancy.
  139. SYSTEM.CHARSET    is identical to the file supplied with the Development  
  140.                   System; it is included here only for the sake of 
  141.                   redundancy.  This file is needed on the Vendor Product 
  142.                   Disk only if TURTLEGRAPHICS is used.
  143.  
  144. Of the files supplied on the Run-Time System disks, the final Vendor Product 
  145. Disk should contain only the Run-time P-machine (SYSTEM.APPLE, RTSTND.APPLE, 
  146. or RTSTRP.APPLE), SYSTEM.PASCAL, SYSTEM.LIBRARY, the appropriate MISCINFO file 
  147. renamed to SYSTEM.MISCINFO, and, optionally, SYSTEM.CHARSET.  SYSTEM.ATTACH, 
  148. with its attendant data files should be included on the Vendor Product Disk if 
  149. special device drivers must be bound into the  system for use by the 
  150. Application Package.  All other files on the Run-Time System disks are used in 
  151. creating and configuring the Vendor Product  Disk.
  152.  
  153.  
  154. Operation
  155.  
  156. The term Vendor Product Disk, as used throughout this Technical Note, refers 
  157. to the primary (boot) disk in a turnkey application package, which is assumed 
  158. to contain the following software:  the Run-time P-machine, the Run-time 
  159. Operating system, a SYSTEM.LIBRARY file, a SYSTEM.MISCINFO file, and the files 
  160. comprising the application package's programs (and any necessary data).  In  
  161. most instances, the Vendor Product Disk will be the only software disk in the 
  162. package.  Larger systems, however, may also include other disks that  contain 
  163. additional software and data which will not fit on the boot disk.
  164.  
  165. Note that the main application program must be named SYSTEM.STARTUP, so the 
  166. Run-Time System can find it when booting.
  167.  
  168. A two-stage boot process can be used with the 64K and 128K Run-Time Systems if 
  169. the necessary boot files listed above cannot fit on a single disk.  In this 
  170. case, the primary boot disk would contain only the Run-time P-machine.  A 
  171. second-stage boot disk would contain the remainder of the files.  A two-stage 
  172. boot process cannot be used with the 48K Run-Time System.
  173.  
  174.  
  175. The Boot Process
  176.  
  177. The boot code (contained in blocks 0 and 1 of the boot disk) is loaded into 
  178. memory by the Autostart ROM.  It checks for the P-machine file and loads it 
  179. into RAM.  The P-machine, in turn, brings in and initializes the Run-time 
  180. operating system.  (In the case of a two-stage boot, the message "Insert boot 
  181. disk with SYSTEM.PASCAL on it, then press RETURN" appears after the P-machine 
  182. has been loaded.  The user should then insert the second-stage boot disk and 
  183. press the Return key, which results in the Run-time operating system being 
  184. loaded and initialized.)  The first noteworthy action taken by the operating 
  185. system is to execute SYSTEM.ATTACH, if that utility program is available on 
  186. the Vendor Product Disk.  Remember that SYSTEM.ATTACH must not be present on 
  187. the Vendor Product Disk unless special, low-level I/O drivers must be bound 
  188. into the system.  As explained more fully in Apple II Pascal Device and 
  189. Interrupt Support Tools, SYSTEM.ATTACH uses two special data files and will 
  190. fail if these files are not present on the boot disk.  Putting SYSTEM.ATTACH 
  191. on the Vendor Product Disk without also providing the required data files 
  192. insures consistent failure of the system boot process.  It is possible to 
  193. include SYSTEM.ATTACH on the Vendor Product Disk, while defeating the 
  194. automatic execution of it at boot time, by changing its name.
  195.  
  196. The boot process culminates when the main application program, SYSTEM.STARTUP, 
  197. is loaded and executed.  Any failure during the boot process is fatal.  
  198. Whenever possible, a failure will display the following message:
  199.  
  200. SYSTEM FAILURE NUMBER nn.  PLEASE REFER TO PRODUCT MANUAL.
  201.  
  202. Here, nn refers to the actual number reported when the failure occurs.  This 
  203. number corresponds to one of the following failures:
  204.  
  205.     01 Unable to load specified program
  206.     02 Specified program file not available
  207.     03 Specified program file is not code file
  208.     04 Unable to read block zero of specified file
  209.     05 Specified code file is un-linked
  210.     06 Conflict between user and intrinsic segments
  211.     07 UNASSIGNED ERROR CODE
  212.     08 Required intrinsics not available
  213.     09 System internal inconsistency
  214.     10 Can't load required intrinsics/Can't open library file
  215.     11 Specified code file must be run under the 128K system
  216.     12 Original disk not in boot drive
  217.  
  218. Clearly, these messages are useful as debugging tools as well as in mechanisms 
  219. for field failure reporting.  The Product Manual mentioned in the bootstrap 
  220. failure message is, of course, the vendor's own product  manual.  It is the 
  221. responsibility of the vendor to enumerate and explain for the user the 
  222. situations in which bootstrap failures may occur, as well as suggest remedies 
  223. for these failures.
  224.  
  225.  
  226. General Considerations
  227.  
  228. Once the program is loaded and running, operation proceeds normally and may 
  229. even include removal of the system disk.  (It is, however, the responsibility 
  230. of the application package to protect itself against the possibility that the 
  231. system disk will not be on-line when a segment must be loaded or when a 
  232. specific subprogram must be chained to.  At such times, the application 
  233. software should first determine whether or not the required disk is on-line, 
  234. and, if not, suspend operation, after giving a suitable prompt, until the user 
  235. has inserted the disk in the appropriate drive.)  Any errors that occur during 
  236. execution of the application package cause the system to transfer program 
  237. control to a specific procedure in the currently-executing application 
  238. program, where code intended to respond to errors is assumed to exist.  If any 
  239. program in the application system terminates without chaining to another one, 
  240. the Run-time system reboots into SYSTEM.STARTUP.
  241.  
  242.  
  243. Specifications
  244.  
  245. Available Configurations
  246.  
  247. The memory requirements of different applications impose the need for 
  248. different Run-Time Systems.  The developer should choose one of the systems as 
  249. the target environment, and keep its limitations and capabilities in mind 
  250. during design and implementation of the application package.  Apple currently 
  251. supports the following Run-Time Systems:
  252.  
  253. o    The 48K Run-Time System  V1.2    (standard and stripped)
  254. o    The 64K Run-Time System  V1.3    (standard only)
  255. o    The 128K Run-Time System V1.3    (standard only)
  256.  
  257. The difference between the standard and stripped versions of the 48K Run-Time 
  258. System is that the stripped version does not support set operations or 
  259. floating point arithmetic, thereby making more memory available for the 
  260. application.
  261.  
  262. The chart below summarizes the amount of free memory that is available under 
  263. the different Run-Time Systems for use by the application package.  Note that 
  264. when swapping is set to level 1, the amount of memory available to the 
  265. application package is increased by approximately 3660 bytes.
  266.  
  267.                              |   No Swapping   |   Swapping on
  268.                              |                 |   byte level
  269.            __________________|_________________|_________________                                   
  270.               48K Standard   |   23372 bytes   |   27040 bytes   |
  271.               48K Stripped   |   25676 bytes   |   29344 bytes   |
  272.                   64K        |   40290 bytes   |   43958 bytes   |
  273.               128K (code)    |   40758 bytes   |   44410 bytes   |
  274.               128K (data)    |   44502 bytes   |   44526 bytes   |
  275.  
  276.                     Figure 1-Free Memory in Run-Time Systems
  277.  
  278. Note:    The amount of free memory available with the 64K Run-Time 
  279. System is reduced by 1024 bytes if it is operating in 40-column 
  280. mode.  Similarly, the amount of free memory available for data in 
  281. the 128K Run-Time System is reduced by 1024 bytes if the system is 
  282. operating in 40-column mode.
  283.  
  284. There is another level of swapping (level 2) which provides an additional 810 
  285. bytes of usable memory, however, using GET or PUT to disk will be slow if 
  286. swapping level 2 is selected since these routines will have to be loaded from 
  287. disk repeatedly.  READ and WRITE to disk will also be slow since they use GET 
  288. and PUT.  BLOCKREAD, BLOCKWRITE, UNITREAD, and UNITWRITE will be unaffected.
  289.  
  290. Swapping can be set to the desired level by using RTSETMODE (described later) 
  291. or by calling a procedure in CHAINSTUFF before chaining to another subprogram.  
  292. See the Apple II Pascal 1.3 Manual for further information on swapping.
  293.  
  294. Use Environment
  295.  
  296. The hardware environment must include the following:
  297.  
  298. 48K Run-Time System     An Apple ][ or ][+ with 48K of RAM (minimum), or an 
  299.                         Apple IIe, IIc or IIGS.
  300. 64K Run-Time System     An Apple ][ or ][+ with 48K of RAM and an Apple 
  301.                         Language Card, or an Apple IIe, IIc or IIGS.
  302. 128K Run-Time System    An Apple IIe with an Extended 80-Column Text Card, an 
  303.                         Apple IIc or an Apple IIGS.
  304. All Run-Time Systems    At least one disk drive in slot 4, 5, or 6.  Video 
  305.                         screen or external terminal (video screen preferred).
  306.  
  307. Note that the Run-Time Systems support all standard Apple peripheral cards.  
  308. Other cards may not operate properly, especially if they include firmware that 
  309. depends upon specific internal characteristics of the P-machine or operating 
  310. system.  SYSTEM.ATTACH must be used by those vendors who wish to reconfigure 
  311. the BIOS (Basic I/O Subsystem) to support non-standard peripheral devices.  
  312. Through the ATTACH facility, it is possible to assign new physical devices to 
  313. any of the existing logical I/O units in the Pascal system, as well as retain 
  314. the standard device assignments while adding new devices to the system.  
  315. Drivers prepared for use with SYSTEM.ATTACH are bound into the system 
  316. dynamically when it boots.  Note that the addition of special I/O drivers to 
  317. the system will reduce the amount of free memory available for use by the 
  318. applications code, since drivers are loaded on the Pascal system heap.  For 
  319. more information, see Apple II Pascal Device and Interrupt Support Tools.
  320.  
  321. Restrictions and Considerations
  322.  
  323. 1.    SYSTEM.ATTACH and the CHAINSTUFF, LONGINTIO, and PASCALIO units in 
  324.       SYSTEM.LIBRARY make assumptions about the internal structure of  
  325.       the Pascal operating system.  Because the internals of the Run-
  326.       time operating systems are different from those in the Development 
  327.       System, only the versions  of CHAINSTUFF, LONGINTIO, PASCALIO and 
  328.       SYSTEM.ATTACH that are supplied on the Run-Time System disks 
  329.       should be used in the Run-time execution environment.  (These 
  330.       special versions should never be used in the Development 
  331.       environment.)
  332.  
  333. 2.    The units TRANSCEND and TURTLEGRAPHICS employ floating-point 
  334.       operations, so software intended to be executed under the 48K 
  335.       stripped Run-Time System should not use them.  For software that 
  336.       employs the TURTLEGRAPHICS procedure TURNTO, note that turns 
  337.       through right angles and null angles are treated as special cases, 
  338.       and the TURTLEGRAPHICS unit uses only integer arithmetic in 
  339.       calculating the trigonometric values needed to execute them.  
  340.       TURTLEGRAPHICS may be used under the 48K stripped Run-Time System 
  341.       if the turtle is allowed to make only right-angle turns (i.e., the 
  342.       HILBERT demonstration program on the APPLE3: disk).  Attempts to 
  343.       draw arbitrary curves, as demonstrated in the GRAFDEMO program on 
  344.       APPLE3:, will produce execution errors in the 48K stripped Run-
  345.       time environment. 
  346. 3.    Pascal's special function keys retain their meanings in the Run-
  347.       Time Systems.  The following keys have special meanings:
  348.  
  349.       Control-@               Break
  350.       Control-A               Switch to alternate half of screen
  351.       Control-F               Flush screen display
  352.       Control-S               Freeze (Stop) screen display
  353.       Control-Z               Initiate auto-follow mode
  354.       Control-W, Control-E    Upper/lower case activation
  355.       Control-R, Control-T    Reverse video toggles
  356.       Control-K               Left square bracket 
  357.       Shift-M                 Right square bracket
  358.  
  359.       Note:    Some of these special function keys are ignored by 
  360.       Pascal if it is running on an Apple IIe, IIc or IIGS.  Also, 
  361.       it is possible to disable some of these special key 
  362.       functions.  See Apple II Pascal 1.3 Manual for complete 
  363.       details.
  364.  
  365. 4.    The Run-Time System will operate correctly only with programs that 
  366.       have been prepared for execution in the Apple II Pascal 
  367.       environment.using Apple's Pascal compiler or Pascal-system 
  368.       assembler on either an Apple II or an Apple ///.
  369.  
  370. 5.    The Run-Time System is optimized for operation with Apple's built-
  371.       in video output screen.  There is no easy way for a turnkey 
  372.       package to reconfigure its host Run-Time System to use the random-
  373.       cursor facilities of any arbitrary external terminal.  Therefore, 
  374.       it is expected that users of the system will be operating with the 
  375.       standard Apple video screen and not an external terminal.  Any 
  376.       program that makes use of screen control, such as clearing the 
  377.       screen, random cursor addressing, or backspacing, is not likely to 
  378.       work properly on an external terminal.  To avoid this problem, the 
  379.       Run-Time System contains a switch which can be set through the 
  380.       RTSETMODE program (explained below).  When set, this switch causes 
  381.       the system to ignore an external terminal, if one is connected.  
  382.       Simple programs that do not make use of any screen control may 
  383.       leave the external terminal switched in without any adverse 
  384.       consequences.
  385.  
  386.  
  387. Run-Time System Configuration Utilities
  388.  
  389. RTSETMODE (provided with all Run-Time Systems) 
  390.  
  391. Flags which note the state of four system options are contained within a 
  392. special part of the directory of any Run-Time System boot disk.  (These flags 
  393. will not normally be present on disks prepared for or used with the Pascal 
  394. Development System.)  When a flag is set (TRUE), the corresponding system 
  395. option is enabled.  The option is disabled when the corresponding flag is 
  396. reset (FALSE).  At boot time, the option flags are checked and are used during 
  397. a dynamic configuration process which occurs before the application software 
  398. is executed.
  399.  
  400. The RTSETMODE utility is used by the application developer to set or reset the 
  401. option flags, according to the requirements of the application package.  In 
  402. operating RTSETMODE, the developer first selects the Pascal volume to be 
  403. affected, then answers four yes-or-no questions by pressing the Y or N keys, 
  404. respectively.  Responding to any prompt for input by pressing only the Return 
  405. key causes immediate termination of the program.
  406.  
  407. Answering yes to any of the following questions arms the indicated option 
  408. (setting the corresponding flag), while answering no disarms the option (and 
  409. resets the corresponding flag).
  410.  
  411.       Arm Filehandler Overlay Option?  Arming this option sets OS 
  412.       swapping to level 1.  Operating System code related to disk file 
  413.       opening and closing is swapped into memory as needed by the 
  414.       application software, thus freeing approximately 3660 bytes of RAM 
  415.       for use by the application.
  416.  
  417.       Arm Single-drive System Option?  With this option armed, the 
  418.       initial boot process is finished, the Pascal system will not 
  419.       assume the availability of any disk drives other than the boot 
  420.       drive.  Specifically, volume searches will be limited to the boot 
  421.       drive.  The application may still use Apple Pascal's UNITREAD and 
  422.       UNITWRITE procedures to access any other drives which may be 
  423.       connected to the system.
  424.  
  425.       Arm Ignore External Terminal Option?  Arming this option insures 
  426.       that the Pascal system will always operate in 40-column mode, 
  427.       regardless of whether or not an external terminal interface or 80-
  428.       column card is available.
  429.  
  430.       Arm Get/Put and Filehandler Overlay Option?  Arming this option 
  431.       sets OS swapping to level 2.  Operating System code related to 
  432.       disk file opening and closing, as well as GET and PUT to disk is 
  433.       swapped into memory as needed.  (See above for more information on 
  434.       swapping level 2.)
  435.  
  436. After the four-question sequence, RTSETMODE asks the user to confirm that all 
  437. information input to that point is correct and should be used to update the 
  438. Vendor Product Disk.  If so, an attempt is made to update the disk's directory 
  439. with the new set of option flags, and RTSETMODE finishes by reporting the 
  440. success or failure of the update operation.
  441.  
  442. Developers should note that only exact copies of a Run-time boot disk will 
  443. retain its option flags.  Transferring the Run-Time System and applications 
  444. software from disk to disk on a file-by-file basis will not transfer the 
  445. option flags between the disks.  For this reason, it is recommended that 
  446. RTSETMODE be applied to the product master of any package based on Run-time 
  447. immediately prior to releasing that master to production, to insure the 
  448. correct status of the option flags.
  449.  
  450. If a two-stage boot will be used for a run-time application, RTSETMODE must be 
  451. run on both boot disks since the flags are checked by both the P-machine and 
  452. the operating system.
  453.  
  454. RTBOOTLOAD (48K Run-Time System only)
  455.  
  456. This program is used to transfer to the Vendor Product Disk the proper boot 
  457. code for the chosen 48K Run-time configuration (STND or STRP).  Responding to 
  458. any prompt for input by pressing only the Return key results in immediate 
  459. termination of the program.  RTBOOTLOAD first asks for the name of the file 
  460. which contains the appropriate boot code (either RTBSTND.BOOT or 
  461. RTBSTRP.BOOT).  The filename must be entered exactly as it appears in the 
  462. directory (including a volume prefix if the file is not on the default 
  463. volume), or the program will not be able to find the file, and will repeat its 
  464. request for a filename.  Once it has fetched the boot code, RTBOOTLOAD asks 
  465. for the volume name of the Vendor Product Disk, then waits for the user to 
  466. press the space bar (thus providing the user with an opportunity to insert the 
  467. selected volume, if necessary) before attempting to transfer the boot 
  468. information.  The success or failure of the transfer is reported  before 
  469. RTBOOTLOAD terminates.  This program is only supplied on the 48K Run-Time 
  470. System disk and should never be used to transfer boot information to a disk 
  471. which contains the 64K or 128K Run-Time Systems, as doing so will prevent the 
  472. systems from booting correctly.
  473.  
  474.  
  475. Error Handling 
  476.  
  477. If an error in execution or I/O occurs during program operation, the Run-Time 
  478. System attempts to let the application package itself acknowledge, and if 
  479. possible, recover from the error condition.  As with the Pascal Development 
  480. environment, the application developer is free to use the $I- and $R- compiler 
  481. options to assume localized, programmatic control of the corresponding error 
  482. situations.
  483.  
  484. When the Run-Time System detects an error, it stores the error number in 
  485. IORESULT and calls PROCEDURE NUMBER TWO of the currently-executing program.  
  486. This is the procedure in segment number 1 that has been given the procedure 
  487. number 2 by the compiler.  In other words, it is the first one declared after 
  488. the program heading that is not itself a unit or segment procedure, or within 
  489. a unit or segment procedure.  In a compiler listing, PROCEDURE NUMBER TWO may 
  490. be identified as those lines whose S (segment) number is 1, and whose P 
  491. (procedure) number is 2.
  492.  
  493. PROCEDURE NUMBER TWO may be declared as a forward procedure since the 
  494. procedure number is assigned at the forward declaration.
  495.  
  496. From now on, PROCEDURE NUMBER TWO will usually be called the error handler, 
  497. since it must always be reserved by the application programmer for the sole 
  498. purpose of handling errors.  The error handler may not have any parameters, 
  499. and must always be declared as a PROCEDURE, never as a FUNCTION.
  500.  
  501. The error handler can determine what kind of error has occurred by checking 
  502. the value of the IORESULT function.  In the Development System, this function 
  503. is restricted to containing the codes for any I/O errors that might occur 
  504. during execution.  In the Run-Time Systems, IORESULT has been extended to 
  505. report all system errors, as well as the usual I/O errors.
  506.  
  507. Here are all the values IORESULT can assume during Run-time execution:
  508.  
  509.     00 No error                     100 Unknown Run-time error
  510.     01 Bad block, parity error      101 Value range error
  511.     02 Illegal unit number          102 No procedure in segment table
  512.     03 Illegal I/O request          103 Exit from uncalled procedure
  513.     04 Data-com timeout             104 Stack overflow
  514.     05 Volume went off-line         105 Integer overflow
  515.     06 File lost in directory       106 Divide by zero
  516.     07 Bad file name                107 Nil pointer reference
  517.     08 No room on volume            108 Program interrupted by user
  518.     09 Volume not found             109 System I/O error
  519.     10 File not found               110 User I/O error
  520.     11 Duplicate directory entry    111 Unimplemented instruction
  521.     12 File already open            112 Floating point error
  522.     13 File not open                113 String overflow
  523.     14 Bad input format             114 Programmed HALT
  524.     16 Disk is write-protected      115 Programmed breakpoint
  525.     17 Illegal block number         116 Codespace overflow
  526.     18 Illegal buffer address
  527.     19 Must read a multiple of 512 bytes
  528.     20 Unknown ProFile error
  529.     64 Device error 
  530.  
  531. It is recommended that a program's error handler should simply report system 
  532. error for all cases except those which are relevant to the program.  Global 
  533. state variables in the program may be used to help determine the nature of the 
  534. problem and report it to the user.  Note that a system reboot occurs if an 
  535. attempt is made to exit the program (without chaining to another).
  536.  
  537. After the error handler finishes its operation, control returns to the caller 
  538. of the procedure where the error occurred (unless the error was fatal).  In 
  539. this way, program operation may be continued, cleanly and simply, after an 
  540. error is handled.  The caller of a failure-prone procedure can set and test 
  541. status flags to determine whether or not the called procedure completed its 
  542. operation and either repeat the procedure call or perform an alternative 
  543. action.
  544.  
  545. In developing particularly large systems where program chaining is used, the 
  546. application programmer should remember that each chained program must reserve 
  547. PROCEDURE NUMBER TWO as an error handler.
  548.  
  549. Following are two programming examples.  The first shows a typical error 
  550. handler routine, and the second is a program fragment that demonstrates an 
  551. error recovery technique.
  552.  
  553. (* EXAMPLE #1 -- ERROR HANDLER *)
  554.  
  555.     (* THE FOLLOWING PROCEDURE IS ONLY *)
  556.     (* CALLED BY THE OPERATING SYSTEM *)
  557.  
  558.     PROCEDURE ErrorHandler;
  559.  
  560.         PROCEDURE Message(Space: Boolean; S: String);
  561.         VAR Ch : Char;
  562.         BEGIN (* Message *)
  563.             WriteLn;
  564.             WriteLn('*** ',S);
  565.             IF Space THEN
  566.                 BEGIN
  567.                     Write('*** Press SPACE-BAR to continue');
  568.                 REPEAT
  569.                         Read(Keyboard, Ch)
  570.                     UNTIL ((Ch = ' ') AND (NOT EoLn));
  571.                 END;
  572.             END   (* Message *);
  573.  
  574.         BEGIN (* ErrorHandler *)
  575.             IF (IOResult = 14) THEN
  576.                 Message(True,'That is not a legal integer!')
  577.             ELSE IF (IOResult = 106) THEN
  578.                 Message(True,'Division by zero is impossible!')
  579.             ELSE BEGIN
  580.                 Message(False,'System error.  Please reboot.');
  581.                 WHILE True DO (* Hang *);
  582.             END;
  583.         END   (* ErrorHandler *);
  584.  
  585.         (* END OF EXAMPLE #1 *)
  586.  
  587.  
  588.         (* EXAMPLE #2 -- ERROR RECOVERY USING ERROR HANDLER OF EXAMPLE #1 *)
  589.  
  590.         PROCEDURE Calculator;
  591.         (* Features recovery from input or arithmetic error. *)
  592.          TYPE Order = (First, Second);
  593.         VAR A,B : Integer;
  594.              Flag : Boolean;
  595.  
  596.             PROCEDURE GetNumber(Which: Order; VAR Number: Integer);
  597.             BEGIN
  598.                 Write('Input the');
  599.                 IF (Which = First) THEN
  600.                      Write(' first')
  601.                 ELSE Write(' second');
  602.                 Write(' number: ');
  603.                  Read(Number);  ReadLn;
  604.                  Flag := True;
  605.             END   (* GetNumber *);
  606.  
  607.              PROCEDURE Answer;
  608.                 VAR R : Real;
  609.                 BEGIN
  610.                     R := A / B; (* Bombs if B=0 *)
  611.                     WriteLn;
  612.                     WriteLn(A,' divided by ',B,' is ',R);
  613.                  END   (* Answer *);
  614.  
  615.             BEGIN (* Calculator *)
  616.                 REPEAT
  617.                     Flag := False;
  618.                     WriteLn;
  619.                     WriteLn;
  620.                     REPEAT
  621.                         GetNumber(First,A)
  622.                     UNTIL Flag;
  623.                     Flag := False;
  624.                     WriteLn;
  625.                     REPEAT
  626.                         GetNumber(Second,B)
  627.                     UNTIL Flag;
  628.                     Answer;
  629.                 UNTIL Eof;
  630.             END   (* Calculator *);
  631.  
  632.             (* END EXAMPLE #2 *)
  633.  
  634. To illustrate the effect of the Run-Time System's error handling mechanism, 
  635. here is the interaction between user and machine during a typical run of the 
  636. above Calculator program.  User-input is terminated by a press of the Return 
  637. key in all cases except the first and last.  In the first case, the error 
  638. handler is invoked during the erroneous numeric input.  In the last case, the 
  639. system accepts and acts upon a Control-C signal before the user has a chance 
  640. to press any other keys.
  641.  
  642.       Input the first number: N 
  643.  
  644.       *** That is not a legal integer! 
  645.  
  646.       Input the first number: 16
  647.  
  648.       Input the second number: 0
  649.  
  650.       *** Division by zero is impossible! 
  651.  
  652.       Input the first number: 16 
  653.  
  654.       Input the second number: 2 
  655.  
  656.       16 divided by 2 is 8 
  657.  
  658.       Input the first number: <Control-C> 
  659.  
  660. As soon as the user presses Control-C, the Run-time system detects the end of 
  661. the standard input file (EOF), and reboots (right back into Calculator ).
  662.  
  663.  
  664. Differences between the Pascal Development Systems
  665. and the Run-Time Systems
  666.  
  667. Although the Run-Time Systems will run most Pascal code files exactly as does 
  668. the Pascal Development System, the application developer must be aware of 
  669. important differences between the two environments.  As mentioned above, there 
  670. is no system-level handling of any type of error that may occur, including 
  671. stack overflow, arithmetic errors, or bad disk reads.  It is left to the 
  672. application package to respond to all error conditions.  The typical user will 
  673. not have access to (nor knowledge of) the Pascal Formatter or Filer.
  674.  
  675. Many programs which fit comfortably in the 64K Development System environment 
  676. may fail to execute at all under the 48K Run-Time System due to the difference 
  677. in available user memory.  Similarly, programs developed with the 128K 
  678. Development System may fail to execute under the 64K Run-Time System for the 
  679. same reason.  While large systems can be made to fit within the confines of a 
  680. particular Run-time environment, this is possible only through use of Apple 
  681. Pascal's program segmentation (overlay) and chaining facilities.  It is 
  682. suggested, however, that much thought and care be taken when using chaining 
  683. and segmentation in software design, since these facilities, by their very 
  684. nature, involve time-consuming disk accesses.  Application software that 
  685. abuses chaining or segmentation, or employs them in a careless fashion, may 
  686. easily waste a large amount of time in disk thrashing, especially if swapping 
  687. is being used.  Finally, an application package runs the risk of massive 
  688. failure unless calls to program overlays and chaining are preceded by checks 
  689. that the expected disk is in the appropriate drive.  This is especially 
  690. important when the target machine includes only one disk drive (as is 
  691. frequently the case).
  692.  
  693. The following items are never present in the Run-Time Systems:
  694.  
  695. o    System HOMECURSOR, CLEARSCREEN, and CLEARLINE functions
  696. o    System prompt function
  697. o    Compiler, Assembler, Linker, Editor, and Filer
  698. o    IDSEARCH and TREESEARCH procedures
  699.  
  700. Programs that make use of information stored in specific memory locations 
  701. within the Development System P-machine or that make assumptions about static 
  702. or dynamic memory allocation at the operating system level (i.e., for the 
  703. purpose of accessing system data structures) are likely to function 
  704. incorrectly when executed in the Run-time environment.  This failure to run is 
  705. due to the code reorganization, compaction, and optimization that was 
  706. necessary to produce the Run-Time Systems.
  707.  
  708.  
  709. Creation of Vendor Product Disks
  710.  
  711. The following steps can be used as a guide for creating a Vendor Product Disk:
  712.  
  713. 1.    Format a disk using the Pascal Development System Formatter.
  714. 2.    Transfer the files SYSTEM.APPLE (or RTSTND.APPLE or RTSTRP.APPLE), 
  715.       SYSTEM.PASCAL, SYSTEM.LIBRARY, SYSTEM.MISCINFO, and SYSTEM.CHARSET 
  716.       (if needed) from the Run-Time System disk to the Vendor Product 
  717.       Disk.
  718. 3.    Transfer the code file or files for the application to the Vendor 
  719.       Product Disk.  The main code file for the application must be 
  720.       named SYSTEM.STARTUP.
  721. 4.    Run the Pascal Development System Library program to add any 
  722.       needed library units to SYSTEM.LIBRARY on the Vendor Product  
  723.       Disk.
  724. 5.    Run RTBOOTLOAD to load the appropriate bootstrap code from RT48: 
  725.       onto the Vendor Product Disk.  (48K Run-Time Systems Only)
  726. 6.    Run RTSETMODE if you wish to arm the Filehandler Overlay option, 
  727.       the Single-Drive System option, the Ignore External Terminal 
  728.       option, or the Get/Put and Filehandler Overlay option.
  729.  
  730. Vendor Product Disks, or other disks which contain 48K Run-Time System 
  731. software should be copied using only whole-volume transfer mechanisms, such as 
  732. that provided by the Pascal system Filer.  A succession of individual file 
  733. transfers, or a wildcard transfer (such as transferring #4:= to #5:$), will 
  734. only copy files from one disk to another.  They will not copy the crucial 48K 
  735. Run-time boot code between disks.  Only whole-volume transfers (such as #4: to 
  736. #5:, or SOUP: to NUTS:) will result in complete copies, containing the proper 
  737. boot information.
  738.  
  739. Vendor Product Disks, or other disks which contain 64K or 128K Run-Time System 
  740. software can be copied using either whole volume or individual file transfers 
  741. since they do not contain special bootstrap information.
  742.  
  743.  
  744. Apple FORTRAN and the Run-Time Systems
  745.  
  746. Apple FORTRAN programs will execute correctly under the Apple II Pascal Run-
  747. Time Systems (48K and 64K only), as long as no execution errors or untrapped 
  748. I/O errors occur.  Using only FORTRAN, it is impossible to produce object code 
  749. that contains the specially-placed error-handling procedure to which control 
  750. is transferred in the event of an untrapped error during Run-time execution.  
  751. Furthermore, the FORTRAN Run-Time Support Library includes system-level code 
  752. for handling FORTRAN I/O errors independently of the Apple Pascal system's own 
  753. error-handling facilities.  Execution of this special code will always lead to 
  754. a system reboot in the Run-time environment.
  755.  
  756. Users who wish to provide turnkey packages based on FORTRAN object-code are 
  757. advised to link the FORTRAN object-code to a Pascal host, as explained in the 
  758. Apple FORTRAN Language Reference Manual.  The only live code which the Pascal 
  759. host must contain is the error-handling procedure that the Run-Time Systems 
  760. require for robust execution of turnkey software.
  761.  
  762.  
  763. Further Reference
  764. o    Apple II Pascal 1.3 Manual
  765. o    Apple II Pascal Device and Interrupt Support Tools
  766. o    Apple FORTRAN Language Reference Manual
  767.  
  768.